/*
*  Copyright (C) 2009  Peter Kist & Jan Ripke
*
*  This program is free software: you can redistribute it and/or modify
*  it under the terms of the GNU General Public License as published by
*  the Free Software Foundation, either version 3 of the License, or
*  (at your option) any later version.
*
*  This program is distributed in the hope that it will be useful,
*  but WITHOUT ANY WARRANTY; without even the implied warranty of
*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
*  GNU General Public License for more details.
*
*  You should have received a copy of the GNU General Public License
*  along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

/** \file
* This file contains the interface to the mediator and its related types 
*/

#ifndef __mediator_interface_h
#define __mediator_interface_h 1

#include <boost/shared_ptr.hpp>

/** \namespace galaxy::mediator
* The mediator namespace contains all of the mediator related functionality
*/

namespace galaxy {
    namespace mediator {

        class Request;
        class RequestResult;
        class Event;

        typedef boost::shared_ptr<Request>       RequestPtr;        /**< shared pointer to a Request */
        typedef boost::shared_ptr<RequestResult> RequestResultPtr;  /**< shared pointer to a RequestResult */
        typedef boost::shared_ptr<Event>       EventPtr;        /**< shared pointer to an Event */

        /** Mode in which events are posted.
        * Posted event can be processed IMMEDIATE or DELAYED.
        * \par
        * \b Immediate events are sent directly to the consumer which than handles the event immediately.
        * The caller is responsible for resource (event) allocation and waits until the consumer has handled the
        * event.
        * \par 
        * \b Delayed events are sent to the consumer which then queues a copy of the event. The caller then resumes
        * execution. Asynchroniously the consumer can handle the event and free the resources that are occupied
        * by the copy of the event.
        * \par
        * In terms of threads, IMMEDIATE events will be handled by the caller's thread where as DELAYED events 
        * will (most likely) be processed by another thread.
        */
        typedef enum _postmethod {
            POST_IMMEDIATE = 1,     /**< event handled by caller's thread */ 
            POST_DELAYED   = 2,     /**< event queued and handled by relevant consumer's thread */
        } PostMethod;

        /** predefined categories for events and queries */
        typedef enum _category {
            CATEGORY_INPUT   = 1,   /**< mouse, key and joystick module */
            CATEGORY_AUDIO   = 2,   /**< soundfix and effects module */
            CATEGORY_MUSIC   = 3,   /**< music module */
            CATEGORY_NETWORK = 4,   /**< network module */
            CATEGORY_GFX     = 5,   /**< gfx module */
            CATEGORY_PHYSICS = 6,   /**< physics module */
            CATEGORY_GAME    = 7,   /**< main game (client) module */
            CATEGORY_LOGIC   = 8,   /**< logic module */
            CATEGORY_DEBUG   = 9,   /**< for debug purposes */
        } Category;

        /** Identifies objects that are used by the mediator (such as events and queries) */
        class Identifier {
            int value;      /**< contains category (0xff000000), type (0x00ff0000) and subtype (0x0000ffff) */
        public:
            static const int any;
            static const int none;

            /** match any identifier (*,*,*) */
            Identifier () : value(0) { };
            Identifier (Identifier& id) : value (id.value) { };
            Identifier (Category category, int type, int subtype) {
                value = (category << 24) | ((type << 16) & 0x00ff0000) | (subtype & 0x0000ffff);
            };
            virtual ~Identifier () { };

            Identifier& operator=(const Identifier& id) { value = id.value; return *this; };
            bool operator==(Identifier& id) { return value == id.value; };
            /** implicit converter that returns \b value */
            operator int() { return value; }; 

            /** extracts the category */
            Category category() const { return (Category) ((value >> 24) & 0xff); }; 
            /** extracts the type */
            int type() const { return (value >> 16) & 0xff; };
            /** extracts the subtype */
            int subtype () const { return value & 0xffff; };
        };

    } // namespace mediator
} // galaxy

#endif // __mediator_interface_h